|
(SST) ShlWAPI.pas Version 1.08 |
|---|---|
| Developer Reference |
| Searches a string for the first character not in a list of characters and returns that character's position within the string being searched. |
| Scope |
|---|
| Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas). |
| Syntax | |
|---|---|
 |
function StrSpn(psz : LPCSTR; pszSet : LPCSTR) : Integer; |
| Parameters | |
|---|---|
| psz [in] | Pointer to the null-terminsted string to search for the presence of characters not listed in the following parameter (pszSet). |
| pszSet [in] | Pointer to a null-terminated string that consists of the characters assumed to be present in the first parameter (psz). |
| Return Values |
|---|
| If a character not listed in pszSet is encountered in the string to search (i.e. psz), the function returns that character's 0-based index within the string that was searched (i.e. psz). If all characters that constitute the string that was searched were listed in pszSet, the function returns the length of the searched string, without the terminating null character. |
| Remarks |
|---|
| The comparison of the characters listed in pszSet with those in the string being searched (i.e. psz) is case sensitive. For example, if the string being searched contains both an upper and lower case w (i.e. "w" and "W"), but only a lower case w is listed in pszSet, the function will return the 0-based index of the first upper case w (i.e. "W") in psz it encounters. |
| The characters in pszSet can be listed in any sequence. That is they do not have to be sorted alphabetically or according to any other criteria (e.g. ANSI/ASCII ordinal value, etc.). |
| The function is ideally suited to implement functionality similar to that of TMaskEdit controls. |
| Example |
|---|
| PROCEDURE TForm4.TestShlWAPIStrSpn(Sender : TObject); VAR txttosearch : STRING; VAR txttosrchlen : INTEGER; VAR charsettosrch : STRING; VAR apiretval : INTEGER; VAR newinfoline : STRING; BEGIN txttosearch := ''; txttosrchlen := 0; charsettosrch := ''; apiretval := 0; newinfoline := ''; txttosearch := 'AaAAbBBBCCCcDDdD'; //This string consists of the characters //a, A, b, B, c, C, d, and D charsettosrch := 'AbBcCdD'; // <- Note that we've listed all characters // except for the lower case "a" newinfoline := 'StrSpn called with "' + txttosearch + '" and "' + charsettosrch + '"'; Memo1.Lines.Add(newinfoline); apiretval := StrSpn(PChar(txttosearch), PChar(charsettosrch)); newinfoline := 'StrSpn returned ' + IntToStr(apiretval); Memo1.Lines.Add(newinfoline); txttosearch := 'AaAAbBBBCCCcDDdD'; //This string consists of the characters //a, A, b, B, c, C, d, and D charsettosrch := 'AabBcdD'; // <- Note that we've listed all characters except for the upper case "C" newinfoline := 'StrSpn called with "' + txttosearch + '" and "' + charsettosrch + '"'; Memo1.Lines.Add(newinfoline); apiretval := StrSpn(PChar(txttosearch), PChar(charsettosrch)); newinfoline := 'StrSpn returned ' + IntToStr(apiretval); Memo1.Lines.Add(newinfoline); txttosearch := 'It is not entirely clear what this function does.'; charsettosrch := 'cdefh Iiost'; //Note, that this string includes a blank, //but not a lower case "n" newinfoline := 'StrSpn called with "' + txttosearch + '" and "' + charsettosrch + '"'; Memo1.Lines.Add(newinfoline); apiretval := StrSpn(PChar(txttosearch), PChar(charsettosrch)); newinfoline := 'StrSpn returned ' + IntToStr(apiretval); Memo1.Lines.Add(newinfoline); txttosearch := 'It is not entirely clear what this function does.'; txttosrchlen := Length(txttosearch); charsettosrch := 'acdefhI. ilnorstuwy'; //Here we've listed all characters that occur //in the sentence we're searching newinfoline := 'StrSpn called with "' + txttosearch + '" and "' + charsettosrch + '"'; Memo1.Lines.Add(newinfoline); apiretval := StrSpn(PChar(txttosearch), PChar(charsettosrch)); newinfoline := 'StrSpn returned ' + IntToStr(apiretval); IF apiretval <> txttosrchlen THEN newinfoline := 'StrSpn returned ' + IntToStr(apiretval) ELSE newinfoline := 'StrSpn did not find any characters in txttosearch that were not listed in variable charsettosrch.'; Memo1.Lines.Add(newinfoline); Memo1.Lines.Add(''); END; |
| The above example produces the following output: |
| StrSpn called with "AaAAbBBBCCCcDDdD" and "AbBcCdD" StrSpn returned 1 StrSpn called with "AaAAbBBBCCCcDDdD" and "AabBcdD" StrSpn returned 8 StrSpn called with "It is not entirely clear what this function does." and "cdefh Iiost" StrSpn returned 6 StrSpn called with "It is not entirely clear what this function does." and "acdefhI. ilnorstuwy" StrSpn did not find any characters in txttosearch that were not listed in variable charsettosrch. |
| Requirements | |
|---|---|
| Unit: | Declared and imported in (SST)ShlWAPI.pas |
| Library: | (SST)ShlWAPI.dcu/(SST)ShlWAPI.obj |
| Unicode: | Implemented as ANSI (StrSpn and StrSpnA) and Unicode (StrSpnW) functions. |
| Min. ShlWAPI.dll version according to MS SDK doc.: | 4.71 |
| Min. ShlWAPI.dll version based on SST research: | 4.71 |
| Min. OS version(s) according to Microsoft SDK doc.: | Windows 2000, Windows NT 4.0 with Internet Explorer 4.0, Windows 98, Windows 95 with Internet Explorer 4.0 |
| Min. OS version(s) according to SST research.: | Windows NT 4.0 with IE 4.0, Windows 95 with IE 4.0, Windows 98, Windows 2000 and later |
|
Document/Contents version 1.00 Page/URI last updated on 07.12.2023 |
Copyright © Stoelzel Software Technologie (SST) 2010 - 2017 |
Suggestions and comments mail to: webmaster@stoelzelsoftwaretech.com |